<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="../../../assets/docs.css" rel="stylesheet" type="text/css" media="screen" />
<title>MooTools 1.3 参考文档 - Request/Request</title>
</head>

<body>
  <div id="docs" class="doc">
    <div class="methods">
      <h4 class="menu-item"><a href="#Request">Request</a></h4>
      <div class="menu-item"><a href="#Request:setHeader">setHeader</a></div>
      <div class="menu-item"><a href="#Request:getHeader">getHeader</a></div>
      <div class="menu-item"><a href="#Request:send">send</a></div>
      <div class="menu-item"><a href="#Request:cancel">cancel</a></div>
      <div class="menu-item"><a href="#Request:isRunning">isRunning</a></div>
      <h4 class="menu-item"><a href="#Element-Properties">Element.Properties</a></h4>
      <div class="menu-item"><a href="#Element-Properties:send">send</a></div>
      <h4 class="menu-item"><a href="#Element">Element</a></h4>
      <div class="menu-item"><a href="#Element:send">send</a></div>
    </div>
    <div class="l-border r-border span-15 content">
      <h1 id="Request"><a href="#Request">类: Request</a></h1>
      <p class="description">对XMLHttpRequest的封装类.</p>
      <h3>实现:</h3>
      <p><a href="../../../docs/core/Class/Class.Extras.html#Chain">Chain</a>, <a href="../../../docs/core/Class/Class.Extras.html#Events">Events</a>, <a href="../../../docs/core/Class/Class.Extras.html#Options">Options</a></p>
      <h3>语法: </h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">[</span>options<span class="br0">]</span><span class="br0">)</span>;

</pre>
      <h3>参数: </h3>
      <ol>
        <li>options - (<em>object</em>, 可选) 详见下文.</li>
      </ol>
      <h3>Options:</h3>
      <ul>
        <li>url        - (<em>string</em>: 默认为 null) 请求的目标URL. (提示,也可以是<a href="../../../docs/more/Types/URI.html">URI</a>的实例)</li>
        <li>method     - (<em>string</em>: 默认为 'post') HTTP请求方式, 可以为 'post' 或 'get'.</li>
        <li>data       - (<em>string</em>: 默认为 '') 在无给定数据时,为<a href="#Request:send">Request:send</a>提供的默认参数.</li>
        <li>link       - (<em>string</em>: 默认为 'ignore') 可以为 'ignore', 'cancel' 和 'chain'.
          <ul>
            <li>'ignore' - 当请求正在执行时,新请求将被忽略. (与 1.11 的 'wait': true 同效)</li>
            <li>'cancel' - 当请求正在执行时,立即取消当前正在执行的请求,并执行新请求. (与 1.11 的 'wait': false 同效)</li>
            <li>'chain'  - 当请求正在执行时,新请求将被链接注册, 并将在当前请求完成后依次的被执行.</li>
          </ul>
        </li>
        <li>async      - (<em>boolean</em>: 默认为 true) 如果设为false, 请求将是同步的且在请求时堵塞浏览器.</li>
        <li>encoding   - (<em>string</em>: 默认为 'utf-8') 请求的编码方式.</li>
        <li>headers    - (<em>object</em>) 请求头数据.</li>
        <li>isSuccess  - (<em>function</em>) 覆盖内置的isSuccess方法(提示,主要用来自定义请求成功的判断规则).</li>
        <li>evalScripts  - (<em>boolean</em>: 默认为 false) 如果设为true, 响应内容内的 <code>script</code> 标签将被解析执行.</li>
        <li>evalResponse - (<em>boolean</em>: 默认为 false) 如果设为true, 响应内容将被作为纯脚本代码整体解析执行(提示,仅当响应头的 Content-type 为 'javascript' 或 'ecmascript' 时有效).</li>
        <li>emulation  - (<em>boolean</em>: 默认为 true) 如果设为true, method 若不是 'post' 或 'get' 则将强制请求方式为'post',同时新增post数据 '_method' : method (rails 里会使用)</li>
        <li>urlEncoded - (<em>boolean</em>: 默认为 true) 如果设为true, Content-type头将会设置为 www-form-urlencoded + encoding 形式(提醒,仅当请求方式为 'post' 或 'put' 时有效).</li>
        <li>timeout - (<em>integer</em>: 默认为 0) 结合 <code>onTimeout</code> 事件, 用来判定连接超时的毫秒数. (建议不要在大文件请求时使用timeout,除非自己很清楚需要这么做)</li>
        <li>noCache - (<em>boolean</em>; 默认为 false) 如果为 <em>true</em>, 请求参数自动追加一个唯一随机值来防止缓存. (IE有个很不好的坏习惯,对ajax请求数据缓存. 设置参数 <em>noCache</em> 为 true 就能阻止其缓存. 服务器端应该忽略此 <em>noCache</em> 参数.)</li>
        <li>user - (<em>string</em>: 默认为 undefined) When username is set the Request will open with credentials and try to authenticate.</li>
        <li>password - (<em>string</em>: 默认为 undefined) You can use this option together with the <code>user</code> option to set authentication credentials when necessary. Note that the password will be passed as plain text and is therefore readable by anyone through the source code. It is therefore encouraged to use this option carefully</li>
      </ul>
      <h3>Events:</h3>
      <h4>request</h4>
      <p>Fired when the Request is sent.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onRequest<span class="br0">(</span><span class="br0">)</span>
</pre>
      <h4>loadstart</h4>
      <p>Fired when the Request loaded, right before any progress starts. (This is limited to Browsers that support the event. At this time: Gecko and WebKit).</p>
      <h5>Signature:</h5>
      <pre class="javascript">onLoadstart<span class="br0">(</span>event, xhr<span class="br0">)</span>
</pre>
      <h5>参数: </h5>
      <ol>
        <li>event - (Event) The loadstart event.</li>
        <li>xhr - (XMLHttpRequest) The transport instance.</li>
      </ol>
      <h4>progress</h4>
      <p>Fired when the Request is making progresses in the download or upload. (This is limited to Browsers that support the event. At this time: Gecko and WebKit).</p>
      <h5>Signature:</h5>
      <pre class="javascript">onProgress<span class="br0">(</span>event, xhr<span class="br0">)</span>

</pre>
      <h5>参数: </h5>
      <ol>
        <li>event - (Event) The progress event, containing currently downloaded bytes and total bytes.</li>
        <li>xhr - (XMLHttpRequest) The transport instance.</li>
      </ol>
      <h3>示例: </h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>

    url: <span class="st0">'image.jpg'</span>,
    onProgress: <span class="kw2">function</span><span class="br0">(</span>event, xhr<span class="br0">)</span> <span class="br0">{</span>
        <span class="kw2">var</span> loaded = event.<span class="me1">loaded</span>, total = event.<span class="me1">total</span>;

&nbsp;
        console.<span class="me1">log</span><span class="br0">(</span>parseInt<span class="br0">(</span>loaded / total * <span class="nu0">100</span>, <span class="nu0">10</span><span class="br0">)</span><span class="br0">)</span>;
    <span class="br0">}</span>
<span class="br0">}</span><span class="br0">)</span>;

&nbsp;
myRequest.<span class="me1">send</span><span class="br0">(</span><span class="br0">)</span>;
</pre>
      <h3>另参考:</h3>
      <ul>
        <li><a href="https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIDOMProgressEvent">MDC: nsIDOMProgressEvent</a></li>
      </ul>
      <h4>complete</h4>
      <p>Fired when the Request is completed.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onComplete<span class="br0">(</span><span class="br0">)</span>
</pre>
      <h4>cancel</h4>
      <p>Fired when a request has been cancelled.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onCancel<span class="br0">(</span><span class="br0">)</span>
</pre>
      <h4>success</h4>
      <p>Fired when the Request is completed successfully.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onSuccess<span class="br0">(</span>responseText, responseXML<span class="br0">)</span>
</pre>
      <h5>参数: </h5>
      <ol>
        <li>responseText - (<em>string</em>) The returned text from the request.</li>
        <li>responseXML  - (<em>mixed</em>) The response XML from the request.</li>
      </ol>
      <h4>failure</h4>
      <p>Fired when the request failed (error status code).</p>
      <h5>Signature:</h5>
      <pre class="javascript">onFailure<span class="br0">(</span>xhr<span class="br0">)</span>
</pre>
      <h5>参数: </h5>
      <p>xhr - (XMLHttpRequest) The transport instance.</p>
      <h4>exception</h4>
      <p>Fired when setting a request header fails.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onException<span class="br0">(</span>headerName, value<span class="br0">)</span>

</pre>
      <h5>参数: </h5>
      <ol>
        <li>headerName - (<em>string</em>) The name of the failing header.</li>
        <li>value      - (<em>string</em>) The value of the failing header.</li>
      </ol>
      <h3>Properties:</h3>
      <ul>
        <li>response - (<em>object</em>) Object with text and XML as keys. You can access this property in the 'success' event.</li>
      </ul>
      <h3>返回值: </h3>
      <ul>
        <li>(<em>object</em>) A new Request instance.</li>
      </ul>
      <h3>示例: </h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>method: <span class="st0">'get'</span>, url: <span class="st0">'requestHandler.php'</span><span class="br0">}</span><span class="br0">)</span>;
myRequest.<span class="me1">send</span><span class="br0">(</span><span class="st0">'name=john&amp;lastname=dorian'</span><span class="br0">)</span>;

</pre>
      <h3>另参考:</h3>
      <ul>
        <li><a href="http://en.wikipedia.org/wiki/XMLHttpRequest">Wikipedia: XMLHttpRequest</a></li>
      </ul>
      <h4>timeout</h4>
      <p>Fired when a request doesn't change state for <code>options.timeout</code> milliseconds.</p>
      <h5>Signature:</h5>
      <pre class="javascript">onTimeout<span class="br0">(</span><span class="br0">)</span>
</pre>
      <h2 id="Request:setHeader"><a href="#Request:setHeader">Request Method: setHeader</a></h2>
      <p class="description">Add or modify a header for the request. It will not override headers from the options.</p>
      <h3>语法: </h3>
      <pre class="javascript">myRequest.<span class="me1">setHeader</span><span class="br0">(</span><span class="kw3">name</span>, value<span class="br0">)</span>;
</pre>
      <h3>参数: </h3>
      <ol>
        <li>name  - (<em>string</em>) The name for the header.</li>
        <li>value - (<em>string</em>) The value to be assigned.</li>
      </ol>
      <h3>返回值: </h3>
      <ul>
        <li>(<em>object</em>) This Request instance.</li>
      </ul>
      <h3>示例: </h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'getData.php'</span>, method: <span class="st0">'get'</span>, headers: <span class="br0">{</span><span class="st0">'X-Request'</span>: <span class="st0">'JSON'</span><span class="br0">}</span><span class="br0">}</span><span class="br0">)</span>;
myRequest.<span class="me1">setHeader</span><span class="br0">(</span><span class="st0">'Last-Modified'</span>,<span class="st0">'Sat, 1 Jan 2005 05:00:00 GMT'</span><span class="br0">)</span>;

</pre>
      <h2 id="Request:getHeader"><a href="#Request:getHeader">Request Method: getHeader</a></h2>
      <p class="description">Returns the given response header or null if not found.</p>
      <h3>语法: </h3>
      <pre class="javascript">myRequest.<span class="me1">getHeader</span><span class="br0">(</span><span class="kw3">name</span><span class="br0">)</span>;

</pre>
      <h3>参数: </h3>
      <ol>
        <li>name - (<em>string</em>) The name of the header to retrieve the value of.</li>
      </ol>
      <h3>返回值: </h3>
      <ul>
        <li>(<em>string</em>) The value of the retrieved header.</li>
        <li>(<em>null</em>) <code>null</code> if the header is not found.</li>
      </ul>
      <h3>示例: </h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'getData.php'</span>, method: <span class="st0">'get'</span>, onSuccess: <span class="kw2">function</span><span class="br0">(</span>responseText, responseXML<span class="br0">)</span> <span class="br0">{</span>

    <span class="kw3">alert</span><span class="br0">(</span><span class="kw1">this</span>.<span class="me1">getHeader</span><span class="br0">(</span><span class="st0">'Date'</span><span class="br0">)</span><span class="br0">)</span>; <span class="co1">// alerts the server date (for example, 'Thu, 26 Feb 2009 20:26:06 GMT')</span>
<span class="br0">}</span><span class="br0">}</span><span class="br0">)</span>;

</pre>
      <h2 id="Request:send"><a href="#Request:send">Request Method: send</a></h2>
      <p class="description">Opens the Request connection and sends the provided data with the specified options.</p>
      <h3>语法: </h3>
      <pre class="javascript">myRequest.<span class="me1">send</span><span class="br0">(</span><span class="br0">[</span>options<span class="br0">]</span><span class="br0">)</span>;

</pre>
      <h3>参数: </h3>
      <ol>
        <li>options - (<em>object</em>, 可选) The options for the sent Request.  Will also accept data as a query string for compatibility reasons.</li>
      </ol>
      <h3>返回值: </h3>
      <ul>
        <li>(<em>object</em>) This Request instance.</li>
      </ul>
      <h3>示例: </h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'http://localhost/some_url'</span><span class="br0">}</span><span class="br0">)</span>.<span class="me1">send</span><span class="br0">(</span><span class="st0">'save=username&amp;name=John'</span><span class="br0">)</span>;

</pre>
      <h3>提示:</h3>
      <p>MooTools provides several aliases for <a href="#Request:send">Request:send</a> to make it easier to use different methods. These aliases are post() and POST(), get() and GET(), put() and PUT() and delete() and DELETE().</p>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'http://localhost/some_url'</span><span class="br0">}</span><span class="br0">)</span>;

&nbsp;
myRequest.<span class="me1">post</span><span class="br0">(</span><span class="st0">'save=username&amp;name=John'</span><span class="br0">)</span>;
<span class="co1">//...is equivalent to:</span>
myRequest.<span class="me1">send</span><span class="br0">(</span><span class="br0">{</span>
    method: <span class="st0">'post'</span>,
    data: <span class="st0">'save=username&amp;name=John'</span>

<span class="br0">}</span><span class="br0">)</span>;
&nbsp;
myRequest.<span class="me1">get</span><span class="br0">(</span><span class="st0">'save=username&amp;name=John'</span><span class="br0">)</span>;
<span class="co1">//...is equivalent to:</span>
myRequest.<span class="me1">send</span><span class="br0">(</span><span class="br0">{</span>

    method: <span class="st0">'get'</span>,
    data: <span class="st0">'save=username&amp;name=John'</span>
<span class="br0">}</span><span class="br0">)</span>;
</pre>
      <h2 id="Request:cancel"><a href="#Request:cancel">Request Method: cancel</a></h2>
      <p class="description">Cancels the currently running request, if any.</p>
      <h3>语法: </h3>
      <pre class="javascript">myRequest.<span class="me1">cancel</span><span class="br0">(</span><span class="br0">)</span>;
</pre>
      <h3>返回值: </h3>
      <ul>
        <li>(<em>object</em>) This Request instance.</li>
      </ul>
      <h3>示例: </h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'mypage.html'</span>, method: <span class="st0">'get'</span><span class="br0">}</span><span class="br0">)</span>.<span class="me1">send</span><span class="br0">(</span><span class="st0">'some=data'</span><span class="br0">)</span>;
myRequest.<span class="me1">cancel</span><span class="br0">(</span><span class="br0">)</span>;

</pre>
      <h2 id="Request:isRunning"><a href="#Request:isRunning">Request Method: isRunning</a></h2>
      <p class="description">Returns true if the request is currently running</p>
      <h3>语法: </h3>
      <pre class="javascript">myRequest.<span class="me1">isRunning</span><span class="br0">(</span><span class="br0">)</span>
</pre>
      <h3>返回值: </h3>
      <ul>
        <li>(<em>boolean</em>) True if the request is running</li>
      </ul>
      <h3>示例: </h3>
      <pre class="javascript"><span class="kw2">var</span> myRequest = <span class="kw2">new</span> Request<span class="br0">(</span><span class="br0">{</span>url: <span class="st0">'mypage.html'</span>, method: <span class="st0">'get'</span><span class="br0">}</span><span class="br0">)</span>.<span class="me1">send</span><span class="br0">(</span><span class="st0">'some=data'</span><span class="br0">)</span>;

&nbsp;
<span class="kw1">if</span> <span class="br0">(</span>myRequest.<span class="me1">isRunning</span><span class="br0">(</span><span class="br0">)</span><span class="br0">)</span> <span class="co1">// It runs!</span>
</pre>
      <h1 id="Element-Properties"><a href="#Element-Properties">Object: Element.Properties</a></h1>
      <p class="description">see <a href="../../../docs/core/Element/Element.html#Element-Properties">Element.Properties</a></p>
      <h2 id="Element-Properties:send"><a href="#Element-Properties:send">Element Property: send</a></h2>
      <h3 class="description">Setter</h3>
      <p>Sets a default Request instance for an Element.  This is useful when handling forms.</p>
      <h4>语法: </h4>
      <pre class="javascript">el.<span class="me1">set</span><span class="br0">(</span><span class="st0">'send'</span><span class="br0">[</span>, options<span class="br0">]</span><span class="br0">)</span>;

</pre>
      <h4>参数: </h4>
      <ol>
        <li>options - (<em>object</em>) The Request options.</li>
      </ol>
      <h4>返回值: </h4>
      <ul>
        <li>(<em>element</em>) The original element.</li>
      </ul>
      <h4>示例: </h4>
      <pre class="javascript">myForm.<span class="me1">set</span><span class="br0">(</span><span class="st0">'send'</span>, <span class="br0">{</span>url: <span class="st0">'contact.php'</span>, method: <span class="st0">'get'</span><span class="br0">}</span><span class="br0">)</span>;
myForm.<span class="me1">send</span><span class="br0">(</span><span class="br0">)</span>; <span class="co1">//Sends the form.</span>

</pre>
      <h3>Getter</h3>
      <p>Returns the previously set Request instance (or a new one with default options).</p>
      <h4>语法: </h4>
      <pre class="javascript">el.<span class="me1">get</span><span class="br0">(</span><span class="st0">'send'</span><span class="br0">)</span>;

</pre>
      <h4>参数: </h4>
      <ol>
        <li>property - (<em>string</em>) the Request property argument.</li>
      </ol>
      <h3>返回值: </h3>
      <ul>
        <li>(<em>object</em>) The Request instance.</li>
      </ul>
      <h4>示例: </h4>
      <pre class="javascript">el.<span class="me1">get</span><span class="br0">(</span><span class="st0">'send'</span>, <span class="br0">{</span>method: <span class="st0">'get'</span><span class="br0">}</span><span class="br0">)</span>;
el.<span class="me1">send</span><span class="br0">(</span><span class="br0">)</span>;
el.<span class="me1">get</span><span class="br0">(</span><span class="st0">'send'</span><span class="br0">)</span>; <span class="co1">// returns the Request instance.</span>

</pre>
      <h1 id="Element"><a href="#Element">类型: Element</a></h1>
      <p class="description">Custom Type to allow all of its methods to be used with any DOM element via the dollar function <a href="../../../docs/core/Element/Element.html#Window:dollar">$</a>.</p>
      <h2 id="Element:send"><a href="#Element:send">Element Method: send</a></h2>
      <p class="description">Sends a form or a container of inputs with an HTML request.</p>
      <h3>语法: </h3>
      <pre class="javascript">myElement.<span class="me1">send</span><span class="br0">(</span>url<span class="br0">)</span>;
</pre>
      <h3>参数: </h3>
      <ol>
        <li>url - (<em>string</em>, 可选) The url you want to send the form or the "container of inputs" to. If url is omitted, the action of the form will be used. url cannot be omitted for "container of inputs".</li>
      </ol>
      <h3>返回值: </h3>
      <ul>
        <li>(element) This Element.</li>
      </ul>
      <h3>示例: </h3>
      <h5>HTML</h5>
      <pre class="javascript">&lt;form id=<span class="st0">"myForm"</span> action=<span class="st0">"submit.php"</span>&gt;

    &lt;p&gt;
        &lt;input <span class="kw3">name</span>=<span class="st0">"email"</span> value=<span class="st0">"bob@bob.com"</span> /&gt;
        &lt;input <span class="kw3">name</span>=<span class="st0">"zipCode"</span> value=<span class="st0">"90210"</span> /&gt;

    &lt;/p&gt;
&lt;/form&gt;
</pre>
      <h5>JavaScript</h5>
      <pre class="javascript">$<span class="br0">(</span><span class="st0">'myForm'</span><span class="br0">)</span>.<span class="me1">send</span><span class="br0">(</span><span class="br0">)</span>;

</pre>
      <h3>Note:</h3>
      <ul>
        <li>The URL is taken from the action attribute of the form.</li>
      </ul>
    </div>
  </div>
<script type="text/javascript" src="../../../assets/mootools-core-1.3.js"></script>
<script type="text/javascript" src="../../../assets/mootools-more-smoothscroll.js"></script>
<script type="text/javascript" src="../../../assets/doc-assist.js"></script>
</body>
</html>
